﻿<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN" 
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">


<!--
E:\DevTools\docbookx.dtd
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
"file:///e:/DevTools/docbookx.dtd">
-->

<book>
  <bookinfo>
    <title>ConfigManager.Net</title>
    <abstract>
      <para>A utility to aid in the management of app.config and web.config files in a team development environment.</para>
    </abstract>
  </bookinfo>

  <preface>
    <title>Preface</title>
    <para>
      ConfigManager.Net executes embedded instructions in the app.config\web.config. 
      These instructions are stored in the file as XML comments and executed in place. 
      A number of instructions are supported to allow you to copy in sections of other
      XML file or XML fragments, change values within the config file or remove sections
      of the config file.
    </para>
  </preface>

  <chapter>
    <title>Instructions</title>
    <sect1>
      <title>Insert</title>
      <para>
        Inserts an XML fragment from another file into the config file. This instruction can be used
        to copy nodes from another xml file.
      </para>
    
      <table>
        <title>Parameters for the Insert Instruction</title>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Parameter</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry>file</entry>
              <entry>Yes</entry>
              <entry>The external file the XML fragment is in.</entry>
            </row>
            <row>
              <entry>xpath</entry>
              <entry>No</entry>
              <entry>The xpath to the fragment in the external file. If this is not provided, the entire external file is inserted.</entry>
            </row>
          </tbody>
        </tgroup>
      </table> 
    </sect1>

    <sect1>
      <title>Set</title>
      <para>Sets the value of a XML Node.</para>

      <table>
      <title>Parameters for the Set Instruction</title>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Parameter</entry>
            <entry>Mandatory</entry>
            <entry>Description</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>xpath</entry>
            <entry>Yes</entry>
            <entry>The xpath of the node we want to change.</entry>
          </row>
          <row>
            <entry>value</entry>
            <entry>Yes</entry>
            <entry>The new value for the node.</entry>
          </row>
        </tbody>
      </tgroup>
      </table>


    </sect1>

    <sect1>
      <title>Delete</title>
      <para>Deletes a XML Node.</para>

      <table>
        <title>Parameters for the Delete Instruction</title>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Parameter</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry>xpath</entry>
              <entry>Yes</entry>
              <entry>The xpath of the node we want to delete.</entry>
            </row>
          </tbody>
        </tgroup>
      </table>
    </sect1>
    
  </chapter>

  <chapter>
    <title>Properties</title>

    <para>
      A property can be used anywhere in an instruction. This is done by placing the 
      property name between "$(" and ")" in the instruction.ConfigManager.Net has the 
      following types of properties:
    </para>
    
    <itemizedlist>
      <listitem>
        <para>
          Properties passed in via the command line can be accessed with the prefix <code>cmdline.</code>
        </para>
      </listitem>
      <listitem>
        <para>
          The envoirnment variables can be accessed with the prefix <code>env.</code> e.g. <code>$(env.path)</code>
        </para>
      </listitem>
      <listitem>
        <para>
          The built-in properties can be accessed with the prefix <code>builtin.</code> 
          e.g. <code>$(builtin.OSVersion)</code>
        </para>
      </listitem>
    </itemizedlist>

    <sect1>
      <title>Builtin Properties</title>
      <table>
        <title>Builtin Properties</title>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Property</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry>CurrentDirectory</entry>
              <entry>The fully qualified path of the current working directory.</entry>
            </row>
            <row>
              <entry>MachineName</entry>
              <entry>The NetBIOS name of this local computer.</entry>
            </row>
            <row>
              <entry>OSVersion</entry>
              <entry>The current platform identifier and version number.</entry>
            </row>
            <row>
              <entry>SystemDirectory</entry>
              <entry>The fully qualified path of the system directory.</entry>
            </row>
            <row>
              <entry>UserDomainName</entry>
              <entry>The network domain name associated with the current user.</entry>
            </row>
            <row>
              <entry>UserName</entry>
              <entry>The user name of the person who is currently logged on to the Windows operating system.</entry>
            </row>
          </tbody>
        </tgroup>
      </table>     
    
    
    
    </sect1>
    
  </chapter>

  <chapter>
    <title>Command Line Options</title>
    <para><code>Config.exe /infile:file [/outfile:file /basedir:dir /prop:prop1=value1 /prop:prop2=value2 ...]</code></para>

    <sect1>
      <title>Options</title>
      <itemizedlist>
        <listitem><para>/infile - (Mandatory) The XML input file.</para></listitem>
        <listitem><para>/outfile - The output file. By default the infile is overwritten.</para></listitem>
        <listitem><para>/basedir - The base directory to use for relative paths in the config file.</para></listitem>
      </itemizedlist>      
    </sect1>
    
    <sect1>
      <title>Examples</title>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis>Run config over the applications config file</emphasis>
          </para>
          <para>
            <code>Config.exe /infile:MyApp.exe.config</code>
          </para>
        </listitem>
      
        <listitem>
          <para>
            <emphasis>Pass additional parameters to config (user=user1, password=pass)</emphasis>
          </para>
          <para>
            <code>Config.exe /infile:MyApp.exe.config /prop:user user1 /prop:password pass</code>
          </para>
        </listitem>
        
      </itemizedlist>      
    </sect1>  
    
  </chapter>

</book>
